Configuration Guide & JSON Schemas

This document provides a comprehensive specification of the configuration subdirectories, JSON file formats, schema fields, and customization mechanics in Void-Builder.

1. Directory Layout & Profile Roles

All configuration files reside in the configs/ directory:

configs/
├── global_build.json        # Master build manifest (repositories, defaults, services)
├── package_rules.json       # Dynamic package matching and injection rules
├── base_customizations.json # System customization baseline (hostname, timezone, locale)
├── presets/                 # Unified build presets (minimal.json, gaming.json, developer.json)
├── hooks/                   # Lifecycle hook script templates (pre-install, post-install, pre-iso)
├── architectures/           # Target architecture profiles (x86_64.json, rpi-aarch64.json)
├── desktops/                # Desktop environment package bundles (gnome.json, xfce.json)
├── kernels/                 # Kernel package selection profiles (linux-lts.json)
├── bootloaders/             # Bootloader installation profiles (grub.json)
├── packages/                # Modular package bundle profiles (dev-tools.json, gaming.json)
├── services/                # Runit service activation profiles (ssh.json, bluetooth.json)
├── live-users/              # Live environment account profiles (admin.json, guest.json)
├── platforms/               # Single-board hardware platform overrides (pinebookpro.json)
├── assets/                  # Artwork, isolinux configuration templates, GRUB fonts
└── custom_files/            # Overlay file tree copied directly into rootfs at /

2. Master Manifest: `global_build.json`

global_build.json defines the foundational baseline settings for every build.

Complete Annotated Schema

{
  "system": {
    "iso_label": "PEPVOID",
    "workdir_base": "workdir",
    "xbps_cache": "cache/xbps"
  },
  "iso": {
    "compression_type": "xz"
  },
  "initramfs": {
    "compression": "xz"
  },
  "boot_title": "Pepvoid Live",
  "boot_cmdline": "quiet splash live.user=live live.autologin rd.live.overlay.overlayfs=1",
  "splash_image": "configs/assets/data/splash.png",
  "repositories": [
    "https://repo-default.voidlinux.org/current",
    "https://repo-default.voidlinux.org/current/musl",
    "https://repo-default.voidlinux.org/current/aarch64"
  ],
  "custom_repositories": [],
  "customizations": {
    "hostname": "pepvoid-live",
    "timezone": "UTC",
    "locale": "en_US.UTF-8",
    "keymap": "us",
    "users": [
      {
        "name": "live",
        "groups": [
          "wheel",
          "audio",
          "video",
          "storage",
          "network"
        ],
        "password": "live"
      }
    ],
    "services": [
      "dbus",
      "NetworkManager",
      "polkitd",
      "bluetoothd",
      "cupsd",
      "avahi-daemon",
      "sshd",
      "chronyd",
      "alsa",
      "acpid",
      "elogind",
      "wpa_supplicant"
    ]
  },
  "common_desktop_packages": [
    "NetworkManager",
    "alsa-firmware",
    "alsa-pipewire",
    "alsa-utils",
    "avahi",
    "blueman",
    "bluez",
    "dbus",
    "elogind",
    "flatpak",
    "git",
    "nano",
    "pipewire",
    "plymouth",
    "polkit",
    "python3",
    "sudo",
    "vim",
    "wpa_supplicant",
    "xorg"
  ],
  "package_sources": {
    "official": [
      "base-system",
      "vim",
      "git",
      "curl",
      "bash-completion",
      "mtools",
      "gptfdisk",
      "efibootmgr",
      "dosfstools",
      "binutils",
      "xz",
      "device-mapper",
      "dhclient",
      "dracut-network",
      "openresolv"
    ]
  }
}

Key Field Descriptions

system.iso_label: Volume identifier string for the ISO9660 volume (PEPVOID).
system.workdir_base: Base working directory for staging files.
system.xbps_cache: Target directory for cached .xbps binary package archives.
boot_cmdline: Linux kernel boot command-line parameters passed by isolinux/GRUB.
repositories: Official Void Linux XBPS mirror URLs evaluated in order.
customizations.services: List of Runit services enabled by symlinking /etc/sv/<service> into /etc/runit/runsvdir/default/.
customizations.users: Account definitions to create during rootfs provisioning.

3. Architecture Profiles (`configs/architectures/`)

Architecture profiles define specific package lists, repositories, or flags for particular architectures.

Example: `configs/architectures/rpi-aarch64.json`

{
  "architecture": "rpi-aarch64",
  "xbps_arch": "aarch64",
  "engine": "PlatformEngine",
  "repositories": [
    "https://repo-default.voidlinux.org/current/aarch64"
  ],
  "package_sources": {
    "official": [
      "rpi-base",
      "rpi-kernel",
      "raspberrypi-userland"
    ]
  }
}

4. Desktop Profiles (`configs/desktops/`)

Desktop profiles specify packages required to build a functional graphical desktop environment.

Example: `configs/desktops/xfce.json`

{
  "desktop_environment": "xfce",
  "display_manager": "lightdm",
  "package_sources": {
    "official": [
      "xfce4",
      "xfce4-panel",
      "xfce4-settings",
      "xfce4-session",
      "xfwm4",
      "xfdesktop",
      "thunar",
      "lightdm",
      "lightdm-gtk-greeter",
      "network-manager-applet",
      "pavucontrol"
    ]
  },
  "customizations": {
    "services": [
      "lightdm",
      "dbus",
      "NetworkManager"
    ]
  }
}

4. Package Bundle Profiles (`configs/software/`)

Package profiles allow modular bundle composition across 16 categories (desktop-essentials, dev-tools, filesystems, multimedia, office, gaming, networking, virtualization, graphics, printing, xorg, wayland, internet, custom-user, base, installer). The optional PeppermintOS application profiles are welcome, suggested, pfetch, and software-center.

Automatic Profile Defaults

Both base.json and filesystems.json are loaded automatically by default for all builds to guarantee base system utilities and filesystem driver compatibility (btrfs-progs, xfsprogs, f2fs-tools, ext4, ntfs-3g, exfatprogs, dosfstools, parted, gptfdisk, etc.).

Package Profile JSON Schema (`packages` + `optional_packages`)

All 16 package profile JSON files follow a clean, standardized schema:

{
  "name": "desktop-essentials",
  "description": "Essential desktop GUI utilities, CLI networking tools, media codecs, archive tools, and rich typography",
  "_comment": "Note: Core desktop utilities are active defaults in 'packages'. Additional desktop helpers (Picom, Feh, Dmenu, Rofi) are listed in 'optional_packages' for easy enablement.",
  "packages": [
    "git",
    "curl",
    "wget",
    "octoxbps",
    "gparted",
    "keepassxc",
    "file-roller",
    "zip",
    "unzip",
    "p7zip",
    "unar",
    "tar",
    "zstd",
    "ffmpeg",
    "gst-plugins-base1",
    "gst-plugins-good1",
    "gst-plugins-bad1",
    "gst-plugins-ugly1",
    "gst-libav",
    "font-inter",
    "noto-fonts-ttf",
    "noto-fonts-cjk",
    "noto-fonts-emoji",
    "dejavu-fonts-ttf",
    "liberation-fonts-ttf",
    "font-awesome",
    "cantarell-fonts",
    "ttf-ubuntu-font-family"
  ],
  "optional_packages": [
    "unrar",
    "picom",
    "feh",
    "dmenu",
    "rofi"
  ]
}

5. Runit Service Profiles (`configs/services/`)

Service profiles allow easily toggling background daemons.

Example: `configs/services/ssh.json`

{
  "service_name": "ssh",
  "package_sources": {
    "official": [
      "openssh"
    ]
  },
  "customizations": {
    "services": [
      "sshd"
    ]
  }
}

6. How to Create a Brand New Desktop Profile

To add a new desktop environment profile (e.g. configs/desktops/pantheon.json):

Create configs/desktops/pantheon.json:

{
  "desktop_environment": "pantheon",
  "package_sources": {
    "official": [
      "pantheon-desktop",
      "lightdm",
      "lightdm-pantheon-greeter",
      "gsettings-desktop-schemas"
    ]
  },
  "customizations": {
    "services": [
      "lightdm",
      "dbus"
    ]
  }
}

Validate the configuration:

python3 cli.py x86_64 -d pantheon --check

Build ISO:

sudo python3 cli.py x86_64 -d pantheon --mode real

7. Custom File Management & Scalable Overlays

Void-Builder provides 3 distinct, scalable mechanisms for copying custom files and directories into the target system:

A. Direct Filesystem Overlay (`configs/overlay/`)

The simplest and most scalable method. Any file or directory placed inside configs/overlay/ is automatically discovered and mirrored directly to the target rootfs at / with attributes preserved and ownership normalized:

configs/overlay/etc/motd -> Copied to /etc/motd
configs/overlay/usr/share/backgrounds/wallpaper.png -> Copied to /usr/share/backgrounds/wallpaper.png
configs/overlay/etc/polkit-1/rules.d/50-custom.rules -> Copied to /etc/polkit-1/rules.d/50-custom.rules

You can also pass external overlay directories on the CLI using --include-dir /path/to/my-overlay.

B. Declarative Structured Copy (`configs/base_customizations.json` & `copy_files`)

For granular control over source, destination, file permissions, and ownership, use declarative copy_files arrays in JSON:

{
  "base_copy_files": [
    {
      "source": "samba",
      "destination": "/etc/samba"
    },
    {
      "source": "scripts/my-helper.sh",
      "destination": "/usr/local/bin/my-helper.sh",
      "mode": "0755",
      "owner": "0:0"
    },
    {
      "source": "sudoers.d",
      "destination": "/etc/sudoers.d",
      "mode": "0440"
    }
  ]
}

Automatic Executable Bits: Any file copied into /usr/bin/, /usr/local/bin/, /etc/cron.*, or ending in .sh automatically receives execution permissions (0755).
Automatic Sudoers Security: Any file copied into /etc/sudoers.d/ is automatically restricted to 0440 mode and owned by root:root.

C. Automatic `/etc/skel` to `/home/<user>` Propagation

When copying configuration files or dotfiles to /etc/skel/ (e.g. skel/.config/xfce4/), Void-Builder automatically propagates these files into the home directories of all created users (e.g. /home/live/, /home/void/) and assigns proper user ownership (chown -R <user>:<user>).

8. Presets & Edition Profiles (`configs/presets/`)

Presets define unified, all-in-one edition specifications that configure desktop environments, package bundle combinations, system defaults, services, and repositories simultaneously.

Example: `configs/presets/rescue-sysadmin.json`

{
  "name": "rescue-sysadmin",
  "description": "System Rescue, Forensics, Network Troubleshooting, and Disk Partitioning Environment",
  "boot_title": "Void Linux Rescue & SysAdmin",
  "desktop": "xfce",
  "package_profiles": [
    "desktop-essentials",
    "filesystems",
    "networking"
  ],
  "additional_packages": [
    "gparted",
    "testdisk",
    "ddrescue",
    "smartmontools",
    "wireshark",
    "nmap",
    "tcpdump",
    "iperf3",
    "chntpw",
    "htop",
    "glances",
    "tmux",
    "rsync"
  ],
  "customizations": {
    "hostname": "void-rescue",
    "services": [
      "sshd",
      "NetworkManager"
    ]
  }
}

9. Lifecycle Hooks Engine (`configs/hooks/`)

Lifecycle hooks allow executing custom shell scripts at four deterministic points during the build:

pre-install: Executed outside the chroot before XBPS installs packages.
post-install: Executed directly inside the chroot environment after package installation and service configuration. Ideal for generating custom version tags, modifying /etc/os-release, or cloning custom dotfiles.
pre-iso: Executed outside the chroot before SquashFS or disk image compression.
post-iso: Executed after the final image, tarball, and checksums are generated.

Hook Example (`configs/hooks/post-install.example.sh`):

#!/bin/sh
# Hook executed inside the chroot
echo "=> Branding custom Void build..."
echo "Void-Builder Custom Workstation v1.0" > /etc/void-custom-release
chmod 0644 /etc/void-custom-release

10. Security Actions & Service Conflict Resolution

The system configurator (SystemConfigurator) automatically manages:

RootPasswordAction: Ingests --root-password <pass> or --lock-root to secure administrative accounts.
SSHKeyAction: Provisions authorized keys into /root/.ssh/authorized_keys and /home/<live_user>/.ssh/authorized_keys with strict permissions (0700 directory, 0600 file).
Service Conflict Engine: Automatically detects if NetworkManager is enabled and suppresses conflicting standalone services like dhcpcd to prevent race conditions during boot.

Configuration Guide & JSON Schemas

1. Directory Layout & Profile Roles

2. Master Manifest: global_build.json

Complete Annotated Schema

Key Field Descriptions

3. Architecture Profiles (configs/architectures/)

Example: configs/architectures/rpi-aarch64.json

4. Desktop Profiles (configs/desktops/)

Example: configs/desktops/xfce.json

4. Package Bundle Profiles (configs/software/)

Automatic Profile Defaults

Package Profile JSON Schema (packages + optional_packages)

5. Runit Service Profiles (configs/services/)

Example: configs/services/ssh.json